edytor 2.0.0 → 4.0.0

package/README.md

@@ -17,11 +17,11 @@
 
 Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable editor with an API to build any kind of collaborative rich text editor.
 
-> **2.0.** Edytor `2.0.0` is on npm as `edytor`: its API follows semantic versioning, and every change is listed in the changelog. It has no production track record yet: read the [limitations](https://edytor.dev/docs/reference/limitations) before you build on it. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **4.0.** Edytor `4.0.0` is on npm as `edytor`: its API follows semantic versioning, and every change is listed in the changelog. It has no production track record yet: read the [limitations](https://edytor.dev/docs/reference/limitations) before you build on it. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
 
 ## Features
 
-- **Notion-style editing out of the box.** `<Edytor />` alone is a rich text editor with block handles: headings, toggle headings, lists, to-dos, toggles, callouts, quotes, dividers, ten marks and Notion's hotkeys. Add the Notion theme, a block menu (block colours; drag one block, or every block the selection covers), a slash menu, a selection toolbar, markdown shortcuts (`createMarkdownShortcutsPlugin()`) code blocks and images (`createImagePlugin({ upload })`).
+- **Notion-style editing out of the box.** `<Edytor />` alone is a rich text editor: headings, toggle headings, lists, to-dos, toggles, callouts, quotes, dividers, ten marks and Notion's hotkeys. Add the Notion theme and the plugins you want: block handles and a block menu (block colours; drag one block, or every block the selection covers), a slash menu, a selection toolbar, markdown shortcuts (`createMarkdownShortcutsPlugin()`), code blocks and images (`createImagePlugin({ upload })`). The package draws no chrome: each handle and menu is your snippet, or the ready-made registry item.
 - **Pages and a table of contents, opt-in.** `createPagePlugin` links a block to another document (a page per room, opened and named by your app), and `createTocPlugin()` lists the headings live ([Page](https://edytor.dev/docs/plugins/page), [Table of contents](https://edytor.dev/docs/plugins/table-of-contents)).
 - **Columns, opt-in.** List `createColumnsPlugin()` for Notion's multi-column layouts: drag a block to the edge of another to put them side by side, or pick "2 columns" to "5 columns"; drag the gap to resize. Layouts converge across collaborators and the room ([Columns](https://edytor.dev/docs/plugins/columns)).
 - **Tables, opt-in.** List `createTablePlugin()` for Notion's simple table: cells of text, <kbd>Tab</kbd> between them, rows and columns added, moved and deleted from the table's edges and grips, resizable columns, header row and column, HTML tables pasted and copied. Concurrent row and column edits converge on every replica ([Table](https://edytor.dev/docs/plugins/table)).
@@ -35,11 +35,12 @@ Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable
 - **Real-time collaboration.** One `EdytorDocument` shared by any number of views, or none (headless). Presence cursors, identity-preserving moves, splits and merges, and undo that only takes back your own edits.
 - **Offline first.** A local IndexedDB copy and cross-tab sync; offline edits survive reloads and reach the server on reconnect.
 - **A Cloudflare Durable Object room.** `edytor/cloudflare` stores in SQLite, acknowledges after the write, binds identity to the socket and hibernates.
+- **Import and export.** `edytor/export` turns a document into HTML or Markdown and back (`toHTML`, `toMarkdown`, `fromHTML`, `textToBlocks`), by each kind's own forms, in the browser, Node or a Worker; HTML import is sanitized ([Import and export](https://edytor.dev/docs/editor/import-export)).
 - **Headless and Worker-safe.** `edytor/crdt/edytor` runs in Node and Workers without Svelte.
 
 ## Install
 
-The pre-release is on npm under the `next` tag. Name the tag: a bare `edytor` is the old, incompatible `0.0.11`.
+Edytor `4.0.0` is on npm under `latest`:
 
 ```bash
 pnpm add edytor
@@ -65,7 +66,21 @@ pnpm add edytor
 
 `<Edytor>` renders on the server and hydrates, so it works in any route. It includes rich text; each other block kind, block moves from the keyboard (`createArrowMovePlugin()`), and file drops (a media plugin given an `upload`) is a plugin you add, here code blocks; nesting blocks (<kbd>Tab</kbd>, drops inside a block) is the `allowNesting` option, off by default. `onChange` hands you the document after every change ([quick start](https://edytor.dev/docs/getting-started/quick-start)).
 
-The package draws no menu, toolbar or block handle: each is a snippet you pass its plugin ([menus and handles](https://edytor.dev/docs/customization/menus)). The demo's Notion-style ones are in [`src/routes/chrome`](https://github.com/beynar/edytor/tree/master/src/routes/chrome), ready to copy into your app ([ready-made menus](https://edytor.dev/docs/customization/ready-made-menus)).
+The package draws no menu, toolbar or block handle: each is a snippet you pass its plugin ([menus and handles](https://edytor.dev/docs/customization/menus)). Notion-style ones, in shadcn-svelte, are a registry item you add to your app (`npx shadcn-svelte@latest add https://edytor.dev/r/edytor-chrome.json`), as plugins for your `<Edytor>` ([ready-made menus](https://edytor.dev/docs/customization/ready-made-menus)).
+
+The fastest way to a full editor is the starter, a [shadcn-svelte](https://www.shadcn-svelte.com) registry item: every plugin, the ready-made menus and handles, comments, and a page with a cover, an icon, a title and typed properties, in one component copied into your app (Tailwind v4 and `shadcn-svelte init` first; [starter editor](https://edytor.dev/docs/starter)):
+
+```sh
+npx shadcn-svelte@latest add https://edytor.dev/r/starter.json
+```
+
+```svelte
+<script>
+	import { StarterEditor } from '$lib/components/edytor/starter/index.js';
+</script>
+
+<StarterEditor />
+```
 
 To collaborate, name a room and a server running the [`edytor/cloudflare` room](https://edytor.dev/docs/server/quick-start):
 

package/dist/block/block.svelte.js

@@ -1,3 +1,4 @@
+import { cleanups } from '../utils.js';
 import { Text } from '../text/text.svelte.js';
 /** Mark an element inside a block's markup as non-editable chrome (`block.void`, a preview's too). */
 export const voidChrome = (node) => {
@@ -336,10 +337,7 @@ export class Block {
         this.edytor.selection.keep(this);
         // A block laid out again with no commit moves the chrome beside it (the overlay measures).
         const unobserve = this.edytor.overlay.observe(node);
-        const onDestroy = this.edytor.plugins.flatMap((plugin) => {
-            const action = plugin.onBlockAttached?.({ node, block: this });
-            return typeof action === 'function' ? [action] : [];
-        });
+        const onDestroy = cleanups(this.edytor.plugins, (plugin) => plugin.onBlockAttached?.({ node, block: this }));
         return {
             destroy: () => {
                 this.#viewState = read(node);

package/dist/clipboard/htmlFlow.d.ts

@@ -1,10 +1,20 @@
-import type { Edytor } from '../edytor.svelte.js';
 import type { Flow } from '../crdt/flow.js';
-import type { BlockDefinition } from '../plugins.js';
-import { type SerializableContent } from '../utils/json.js';
+import { type JSONBlock, type SerializableContent } from '../utils/json.js';
+import type { AtomForms, BlockForms, MarkForms } from './serializeClipboardFragment.js';
 /** What HTML import reads: the kind, mark and atom records, and the document's default child. */
-export type ImportKinds = Pick<Edytor, 'blocks' | 'marks'> & Partial<Pick<Edytor, 'inlineBlocks'>> & {
-    document: Pick<Edytor['document'], 'defaultChild'>;
+export type ImportKinds = {
+    readonly blocks: ReadonlyMap<string, BlockForms>;
+    readonly marks: ReadonlyMap<string, MarkForms>;
+    readonly inlineBlocks?: ReadonlyMap<string, AtomForms>;
+    readonly document: {
+        defaultChild: (parent: string | null) => string;
+    };
+};
+/** A `DOMParser` constructor: the browser's, or a server's (`linkedom`, `jsdom`, `happy-dom`). */
+export type HtmlParser = new () => {
+    parseFromString(html: string, type: 'text/html'): {
+        body: Node | null;
+    };
 };
 type Values = Record<string, SerializableContent>;
 /**
@@ -13,9 +23,10 @@ type Values = Record<string, SerializableContent>;
  * none: an export form written as one (a callout's `<div data-edytor-callout>`)
  * is found by its `parse` hook only.
  */
-export declare const tagOf: (type: string, kind: BlockDefinition, data: Values) => string | undefined;
+export declare const tagOf: (type: string, kind: BlockForms, data: Values) => string | undefined;
 /**
- * External HTML as a flow: the browser parses (inert: no script
+ * External HTML as lines (JSON blocks; a line without a `type` is its
+ * parent's default child): `parser` parses (inert: no script
  * runs, nothing loads), and the tag tables are the records inverted — a
  * catalogue kind's tag per preset (a content-less container takes its
  * default child's tag, one child per text line), a value-less mark's
@@ -27,5 +38,7 @@ export declare const tagOf: (type: string, kind: BlockDefinition, data: Values)
  * atom, never its text. Unknown
  * elements degrade to text runs; whitespace collapses as HTML renders it. `null` when the HTML carries nothing (`flow.shape`).
  */
+export declare const linesOfHtml: (kinds: ImportKinds, html: string | undefined, parser?: HtmlParser | undefined) => JSONBlock[] | null;
+/** External HTML as a flow (the paste's): {@link linesOfHtml}, with the browser's parser. */
 export declare const flowOfHtml: (kinds: ImportKinds, html: string | undefined) => Flow | null;
 export {};

package/dist/clipboard/htmlFlow.js

@@ -1,6 +1,8 @@
 import { colorsOfClasses } from '../block/colors.js';
 import { isTextPart } from '../block/contentRange.js';
 import { jsonBlockToSpec } from '../utils/json.js';
+/** Element and text nodes by their type, not their realm: a server parser's nodes are not this global's. */
+const isElement = (node) => node?.nodeType === 1;
 /** Never content: their text is code, metadata or form state. */
 const SKIP = /^(script|style|template|noscript|svg|math|iframe|object|embed|canvas|video|audio|img|input|button|select|textarea|head|title|meta|link|base)$/;
 /** HTML's block-level elements: they start a line (a kind's tag does too). */
@@ -21,7 +23,7 @@ const sizeOf = (img, side) => {
  * email's tracking pixel). It is text, its `alt`, never a block.
  */
 const isGlyph = (node) => {
-    if (!(node instanceof HTMLElement) || node.localName !== 'img')
+    if (!isElement(node) || node.localName !== 'img')
         return false;
     const alt = node.getAttribute('alt')?.trim() ?? '';
     if (alt && EMOJI_ALT.test(alt) && /[\p{Extended_Pictographic}\p{Regional_Indicator}]/u.test(alt))
@@ -61,7 +63,8 @@ export const tagOf = (type, kind, data) => {
     return undefined;
 };
 /**
- * External HTML as a flow: the browser parses (inert: no script
+ * External HTML as lines (JSON blocks; a line without a `type` is its
+ * parent's default child): `parser` parses (inert: no script
  * runs, nothing loads), and the tag tables are the records inverted — a
  * catalogue kind's tag per preset (a content-less container takes its
  * default child's tag, one child per text line), a value-less mark's
@@ -73,8 +76,8 @@ export const tagOf = (type, kind, data) => {
  * atom, never its text. Unknown
  * elements degrade to text runs; whitespace collapses as HTML renders it. `null` when the HTML carries nothing (`flow.shape`).
  */
-export const flowOfHtml = (kinds, html) => {
-    if (!html || html.length > 8 * 1024 * 1024 || typeof DOMParser === 'undefined')
+export const linesOfHtml = (kinds, html, parser = globalThis.DOMParser) => {
+    if (!html || html.length > 8 * 1024 * 1024 || !parser)
         return null;
     const { blocks, marks } = kinds;
     const atoms = kinds.inlineBlocks ?? new Map();
@@ -99,8 +102,9 @@ export const flowOfHtml = (kinds, html) => {
             return undefined;
         for (const [type, kind] of blocks) {
             const data = kind.parse?.(element);
+            // A kind of lines (a code block) takes its element's text, one child per line.
             if (data)
-                return { type, kind, data };
+                return { type, kind, data, lines: kind.lines ? kind.defaultChild : undefined };
         }
         return byTag.get(element.localName);
     };
@@ -124,11 +128,10 @@ export const flowOfHtml = (kinds, html) => {
         return found;
     };
     // A kind's hook may claim an element of another namespace (an equation's MathML `<math>`).
-    const isBlock = (node) => (node instanceof HTMLElement && BLOCK.test(node.localName)) ||
-        (node instanceof Element && kindOf(node) !== undefined);
+    const isBlock = (node) => isElement(node) && (BLOCK.test(node.localName) || kindOf(node) !== undefined);
     /** A void kind's element (an image): it shows no text, so a line it is met in ends there. */
     const isVoid = (node) => {
-        const claim = node instanceof Element ? kindOf(node) : undefined;
+        const claim = isElement(node) ? kindOf(node) : undefined;
         return claim?.kind.void === true;
     };
     const text = (line, value, marks, pre) => {
@@ -148,16 +151,16 @@ export const flowOfHtml = (kinds, html) => {
             line.content.push(Object.keys(marks).length ? { text: value, marks } : { text: value });
     };
     const inline = (node, at, marks, pre) => {
-        if (node.nodeType === Node.TEXT_NODE)
+        if (node.nodeType === 3)
             return text(at.line(), node.textContent ?? '', marks, pre);
         if (isGlyph(node))
             return text(at.line(), node.getAttribute('alt') ?? '', marks, pre);
         if (isVoid(node))
             return at.apart(node);
-        const atom = node instanceof Element ? atomOf(node) : undefined;
+        const atom = isElement(node) ? atomOf(node) : undefined;
         if (atom)
             return void at.line().content.push(atom);
-        if (!(node instanceof HTMLElement) || SKIP.test(node.localName))
+        if (!isElement(node) || SKIP.test(node.localName))
             return;
         if (node.localName === 'br')
             return text(at.line(), '\n', marks, true);
@@ -286,12 +289,17 @@ export const flowOfHtml = (kinds, html) => {
         // Split: a text line left empty around a void element is not kept.
         return parts.filter((part) => !texts.has(part) || end(part).content.length > 0 || part.children !== undefined);
     };
-    const body = new DOMParser().parseFromString(html, 'text/html').body;
+    const body = new parser().parseFromString(html, 'text/html').body;
+    if (!body)
+        return null;
     const lines = linesOf(body, undefined);
     const carries = (line) => line.content.length > 0 ||
         Boolean(line.children?.some(carries)) ||
         Boolean(line.type && blocks.get(line.type)?.void);
-    return lines.some(carries)
-        ? { lines: lines.map((line) => jsonBlockToSpec(line, true)) }
-        : null;
+    return lines.some(carries) ? lines : null;
+};
+/** External HTML as a flow (the paste's): {@link linesOfHtml}, with the browser's parser. */
+export const flowOfHtml = (kinds, html) => {
+    const lines = linesOfHtml(kinds, html);
+    return lines ? { lines: lines.map((line) => jsonBlockToSpec(line, true)) } : null;
 };

package/dist/clipboard/serializeClipboardFragment.d.ts

@@ -1,9 +1,42 @@
-import type { Edytor } from '../edytor.svelte.js';
-import type { EdytorClipboardFragment } from './types.js';
-/** The records the export reads: each kind, mark and atom declares its own forms. */
-export type ExportKinds = Pick<Edytor, 'blocks' | 'marks' | 'inlineBlocks'>;
+/**
+ * The document's export forms, one reading for the clipboard and for
+ * `toHTML` / `toMarkdown` (`edytor/export`): each kind, mark and atom
+ * declares its own forms (`html`, `plain`, `markdown`; a mark's `tag` and
+ * `attributes`), and this module only walks the blocks. Pure: no view, no
+ * DOM, no Svelte.
+ */
+import type { JSONBlock, SerializableContent } from '../utils/json.js';
+import type { BlockDefinition, InlineBlockDefinition, MarkDefinition } from '../plugins.js';
+import type { EdytorClipboardFragment, JSONContentPart } from './types.js';
+/** A kind's export and import forms: the fields of its record the export and HTML import read. */
+export type BlockForms = Pick<BlockDefinition, 'html' | 'plain' | 'markdown' | 'parse' | 'element' | 'contentElement' | 'void' | 'island' | 'lines' | 'rendersContent' | 'defaultChild' | 'itemKind'> & {
+    /** The data of each way to create the kind: HTML import finds a preset's tag. */
+    presets?: {
+        data?: Record<string, SerializableContent>;
+    }[];
+};
+/** A mark's export and import forms. */
+export type MarkForms = Pick<MarkDefinition, 'tag' | 'attributes' | 'parse' | 'markdown'>;
+/** An atom's export and import forms. */
+export type AtomForms = Pick<InlineBlockDefinition, 'html' | 'plain' | 'markdown' | 'parse'>;
+/** The records the export reads: each kind, mark and atom declares its own forms (a view is one). */
+export type ExportKinds = {
+    readonly blocks: ReadonlyMap<string, BlockForms>;
+    readonly marks: ReadonlyMap<string, MarkForms>;
+    readonly inlineBlocks: ReadonlyMap<string, AtomForms>;
+};
 export declare const encodeClipboardJson: (value: unknown) => string;
 /** `value` escaped for an HTML text or a double-quoted attribute: every kind's export reads it. */
 export declare const escapeHtml: (value: string) => string;
+/** The content as HTML, or as plain text: an atom by its kind's form (`html`, `plain`). */
+export declare const contentOf: (content: JSONContentPart[] | undefined, kinds: ExportKinds, html: boolean) => string;
+/**
+ * How sibling blocks' HTML joins (`edytor/export` wraps a run of list items
+ * in its list): the blocks, their HTML, and their parent's `html` form.
+ * Without one, one after another (the clipboard's).
+ */
+export type SiblingsHtml = (blocks: JSONBlock[], html: string[], parent?: BlockForms['html']) => string;
+/** Blocks as HTML: the clipboard's and `toHTML`'s one reading of the kinds' forms. */
+export declare const blocksToHtml: (blocks: JSONBlock[], kinds: ExportKinds, wrap: SiblingsHtml) => string;
 export declare const serializeClipboardFragmentToPlainText: (fragment: EdytorClipboardFragment, kinds: ExportKinds) => string;
 export declare const serializeClipboardFragmentToHtml: (fragment: EdytorClipboardFragment, kinds: ExportKinds) => string;

package/dist/clipboard/serializeClipboardFragment.js

@@ -19,7 +19,7 @@ const textHtml = (part, kinds) => {
     return html;
 };
 /** The content as HTML, or as plain text: an atom by its kind's form (`html`, `plain`). */
-const contentOf = (content = [], kinds, html) => content
+export const contentOf = (content = [], kinds, html) => content
     .map((part) => {
     if (isTextPart(part))
         return html ? textHtml(part, kinds) : part.text;
@@ -41,9 +41,9 @@ const withClasses = (html, classes) => classes
     })
     : html;
 /** A block and its subtree as HTML (its colours as Notion's classes), or as plain text. */
-const blockOf = (block, kinds, html) => {
+const blockOf = (block, kinds, html, wrap) => {
     const content = contentOf(block.content, kinds, html);
-    const kids = block.children?.map((child) => blockOf(child, kinds, html)) ?? [];
+    const kids = block.children?.map((child) => blockOf(child, kinds, html, wrap)) ?? [];
     const kind = kinds.blocks.get(block.type);
     if (!html) {
         const children = kids.filter(Boolean).join('\n');
@@ -51,8 +51,8 @@ const blockOf = (block, kinds, html) => {
             ? kind.plain(block, content, children)
             : [content, children].filter(Boolean).join('\n');
     }
-    const children = kids.join('');
     const form = kind?.html;
+    const children = wrap ? wrap(block.children ?? [], kids, form) : kids.join('');
     const out = !form
         ? `<p>${content}</p>${children}`
         : typeof form === 'string'
@@ -61,6 +61,8 @@ const blockOf = (block, kinds, html) => {
     // A block's colours as Notion's export names them (`block-color-red`).
     return withClasses(out, colorClasses(block.data));
 };
+/** Blocks as HTML: the clipboard's and `toHTML`'s one reading of the kinds' forms. */
+export const blocksToHtml = (blocks, kinds, wrap) => wrap(blocks, blocks.map((block) => blockOf(block, kinds, true, wrap)));
 export const serializeClipboardFragmentToPlainText = (fragment, kinds) => fragment.kind === 'blocks'
     ? fragment.blocks.map((block) => blockOf(block, kinds, false)).join('\n')
     : contentOf(fragment.content, kinds, false);

package/dist/clipboard/textBlocks.d.ts

@@ -21,5 +21,13 @@ export type TextToBlocksOptions = {
 };
 /** Whether `text` holds block markdown (one line of it is enough), as a paste reads it. */
 export declare const hasBlockMarkdown: (text: string) => boolean;
+/**
+ * One line's kind, data and text, or `null` for a paragraph line: the one
+ * reading of a markdown line's block marker (`edytor/export`'s full reader
+ * reads its lines with it too).
+ */
+export declare const lineKind: (line: string) => (Omit<JSONBlock, "content"> & {
+    text: string;
+}) | null;
 /** `text` as blocks (see the module comment). */
 export declare const textToBlocks: (text: string, { markdown, type }?: TextToBlocksOptions) => JSONBlock[];

package/dist/clipboard/textBlocks.js

@@ -25,8 +25,12 @@ const runs = (text) => {
 const BLOCK_LINE = /^\s*(?:#{1,6}\s|[-*+]\s|\d+[.)]\s|>|```|(?:-{3,}|\*{3,}|_{3,})\s*$)/;
 /** Whether `text` holds block markdown (one line of it is enough), as a paste reads it. */
 export const hasBlockMarkdown = (text) => text.split(/\r?\n/).some((line) => BLOCK_LINE.test(line));
-/** One line's kind, data and text, or `null` for a paragraph line. */
-const lineKind = (line) => {
+/**
+ * One line's kind, data and text, or `null` for a paragraph line: the one
+ * reading of a markdown line's block marker (`edytor/export`'s full reader
+ * reads its lines with it too).
+ */
+export const lineKind = (line) => {
     let m = /^(#{1,6})\s+(.*)$/.exec(line);
     if (m)
         return { type: 'heading', data: { level: `h${Math.min(3, m[1].length)}` }, text: m[2] };

package/dist/cloudflare/DocumentRoom.d.ts

@@ -121,9 +121,11 @@ export declare const DEFAULT_SAVE_AFTER = 2000;
  * Room quotas, each refused with `4413` (`quota: <name>`). The
  * document's size: what its records hold (uncompressed) and the updates the
  * engine holds waiting. An isolate has 128 MB, and the live document takes
- * 18 to 46 bytes of heap per stored byte (prose to one short line per
- * block, its index included; `bench/room-memory.mjs`): 2 MiB is
- * about 100 MB at worst. Raise it for documents of long text.
+ * 15 to 77 bytes of heap per stored byte in Node (prose to one short line
+ * per block, its index included; `bench/room-memory.mjs`; a Worker takes
+ * less): 2 MiB is about 150 to 160 MB at worst, a list of some 23,000 short
+ * blocks (1.25 MiB keeps that near 100 MB). Raise it for documents of long
+ * text, lower it for long lists of short blocks.
  */
 export declare const DEFAULT_MAX_DOCUMENT_BYTES: number;
 /** The share of the document quota past which the room logs its size, by default. */
@@ -364,7 +366,7 @@ export type RoomLogEntry = {
     user: string;
 } | ({
     edytor: 'purge';
-    horizon: number;
+    horizon: number | null;
     bytes: number;
 } & PurgeReport) | {
     edytor: 'quota';
@@ -801,12 +803,14 @@ export declare class AttachedDocument {
      * The purge task, also over RPC (`room.purge.timing`): record an epoch
      * (the state vector, now) when the document changed since the last one,
      * purge what was deleted before the horizon — the newest epoch at least
-     * `purgeAfterDays` old — when it is newer than the last purged, and
-     * re-arm for the next epoch to pass it. Returns what the purge wrote, or
-     * `null` when nothing was past the horizon.
+     * `purgeAfterDays` old — when it is newer than the last purged, with what
+     * the sessions whose history ended deleted (`hist.release.end`; with no
+     * epoch due, those alone, `horizon: null`), and re-arm for the next epoch
+     * to pass it. Returns what the purge wrote, or `null` when nothing was
+     * past the horizon and no session had ended.
      */
     purge(): (PurgeReport & {
-        horizon: number;
+        horizon: number | null;
     }) | null;
     /** The room's counters, also over RPC — see {@link RoomMetrics}. */
     metrics(): RoomMetrics;
@@ -968,7 +972,7 @@ export declare class DocumentRoom<Env = DocumentRoomEnv> extends DurableObject<E
     };
     /** Run the purge task now, also over RPC — see {@link AttachedDocument.purge}. */
     purge(): (PurgeReport & {
-        horizon: number;
+        horizon: number | null;
     }) | null;
     /** Every comment thread, also over RPC — see {@link AttachedDocument.listComments}. */
     listComments(): CommentSnapshot;

package/dist/cloudflare/DocumentRoom.js

@@ -130,9 +130,11 @@ export const DEFAULT_SAVE_AFTER = 2000;
  * Room quotas, each refused with `4413` (`quota: <name>`). The
  * document's size: what its records hold (uncompressed) and the updates the
  * engine holds waiting. An isolate has 128 MB, and the live document takes
- * 18 to 46 bytes of heap per stored byte (prose to one short line per
- * block, its index included; `bench/room-memory.mjs`): 2 MiB is
- * about 100 MB at worst. Raise it for documents of long text.
+ * 15 to 77 bytes of heap per stored byte in Node (prose to one short line
+ * per block, its index included; `bench/room-memory.mjs`; a Worker takes
+ * less): 2 MiB is about 150 to 160 MB at worst, a list of some 23,000 short
+ * blocks (1.25 MiB keeps that near 100 MB). Raise it for documents of long
+ * text, lower it for long lists of short blocks.
  */
 export const DEFAULT_MAX_DOCUMENT_BYTES = 2 * 1024 * 1024;
 /** The share of the document quota past which the room logs its size, by default. */
@@ -480,9 +482,11 @@ export class AttachedDocument {
      * The purge task, also over RPC (`room.purge.timing`): record an epoch
      * (the state vector, now) when the document changed since the last one,
      * purge what was deleted before the horizon — the newest epoch at least
-     * `purgeAfterDays` old — when it is newer than the last purged, and
-     * re-arm for the next epoch to pass it. Returns what the purge wrote, or
-     * `null` when nothing was past the horizon.
+     * `purgeAfterDays` old — when it is newer than the last purged, with what
+     * the sessions whose history ended deleted (`hist.release.end`; with no
+     * epoch due, those alone, `horizon: null`), and re-arm for the next epoch
+     * to pass it. Returns what the purge wrote, or `null` when nothing was
+     * past the horizon and no session had ended.
      */
     purge() {
         return this.room.purge.tick();

package/dist/cloudflare/room/admission.js

@@ -11,7 +11,7 @@
  */
 import { Y } from '../../crdt/engine.js';
 import * as E from '../../crdt/protocol.js';
-import { ChunkLimitError, ChunkSequenceError, CLOSE } from '../../crdt/providers/room.js';
+import { ChunkError, CLOSE } from '../../crdt/providers/room.js';
 import { MAX_WAITING_DELETES, noTimers } from './shared.js';
 import { STORAGE_FAILURE, now, sync, tally } from './context.js';
 import { attributionWrites, BINDING_PREFIX, forgedAttributionDeletes, forgedDeletes, forgedWriters } from './forged.js';
@@ -168,7 +168,7 @@ export class Admission {
         }
         catch (error) {
             this.#chunkReaders.delete(ws);
-            if (error instanceof ChunkLimitError) {
+            if (error instanceof ChunkError && error.limit !== undefined) {
                 return this.#overQuota(ws, attachment.user, 'frame', {
                     bytes: error.total,
                     limit: error.limit
@@ -187,7 +187,7 @@ export class Admission {
                 room.presence.depart(ws);
                 return room.close(ws, CLOSE.fault, 'room busy');
             }
-            if (error instanceof ChunkSequenceError) {
+            if (error instanceof ChunkError) {
                 room.note({ reason: 'internal', detail: `chunks: ${error.message}` });
                 room.presence.depart(ws);
                 return room.close(ws, CLOSE.fault, 'chunk sequence lost');